// 《围棋》作者版权所有。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// 此文件实现作用域。

package types2

import (
	"bytes"
	"cmd/compile/internal/syntax"
	"fmt"
	"io"
	"sort"
	"strings"
	"sync"
)

// 作用域维护一组对象和指向其包含的
// （父）和包含的（子）作用域的链接。对象可以插入
// 并按名称查找。作用域的零值是一个随时可用的
// 空作用域。
type Scope struct {
	parent   *Scope
	children []*Scope
	number   int               // 父母。儿童[1号]是这个范围；如果没有父
	elems    map[string]Object // 延迟分配
	pos, end syntax.Pos        // 作用域范围，则为0；可能无效
	comment  string            // 仅用于调试
	isFunc   bool              // 如果这是函数作用域（仅限内部使用）则设置
}

// 新闻作用域返回给定父
// 作用域中包含的新空作用域（如果有）。此评论仅用于调试。
func NewScope(parent *Scope, pos, end syntax.Pos, comment string) *Scope {
	s := &Scope{parent, nil, 0, nil, pos, end, comment, false}
	// 不要将子对象添加到宇宙范围！
	if parent != nil && parent != Universe {
		parent.children = append(parent.children, s)
		s.number = len(parent.children)
	}
	return s
}

// Parent返回作用域的包含（父）作用域。
func (s *Scope) Parent() *Scope { return s.parent }

// Len返回范围元素的数量。
func (s *Scope) Len() int { return len(s.elems) }

// Names按排序顺序返回作用域的元素名称。
func (s *Scope) Names() []string {
	names := make([]string, len(s.elems))
	i := 0
	for name := range s.elems {
		names[i] = name
		i++
	}
	sort.Strings(names)
	return names
}

// NumChildren返回嵌套在s中的作用域数。
func (s *Scope) NumChildren() int { return len(s.children) }

// Child返回0<=i<NumChildren（）的第i个子作用域。
func (s *Scope) Child(i int) *Scope { return s.children[i] }

// 如果存在这样一个
// 对象，则Lookup返回作用域s中具有给定名称的对象；否则结果为零。
func (s *Scope) Lookup(name string) Object {
	return resolve(name, s.elems[name])
}

// LookupParent遵循从s开始的作用域父链，直到
// 它找到一个作用域，其中Lookup（name）返回一个非零对象，然后
// 返回该作用域和对象。如果提供了有效的pos位置，
// 只考虑在pos或pos之前声明的对象。
// 如果不存在这样的作用域和对象，结果是（nil，nil）。注意obj。如果
// 对象被插入到范围中，并且在该
// 时间（请参见Insert），则Parent（）可能与返回的范围不同。这只适用于点导入的对象
// 其作用域是导出它们的包的作用域。
func (s *Scope) LookupParent(name string, pos syntax.Pos) (*Scope, Object) {
	for ; s != nil; s = s.parent {
		if obj := s.Lookup(name); obj != nil && (!pos.IsKnown() || obj.scopePos().Cmp(pos) <= 0) {
			return s, obj
		}
	}
	return nil, nil
}

// Insert尝试将对象obj插入作用域s。
// 如果s已经包含一个与
// 同名的替代对象alt，Insert将保持s不变并返回alt。
// 否则它将插入obj，设置对象的父作用域
// 如果尚未设置，则返回nil。
func (s *Scope) Insert(obj Object) Object {
	name := obj.Name()
	if alt := s.Lookup(name); alt != nil {
		return alt
	}
	s.insert(name, obj)
	if obj.Parent() == nil {
		obj.setParent(s)
	}
	return nil
}

// InsertLazy类似于Insert，但它允许延迟构建
// inserted对象，直到通过查找访问它。resolve返回的对象
// 必须与InsertLazy同名。
// 如果s已经包含同名的替代对象，则
// InsertLazy将保持s不变并返回false。否则它将记录绑定并返回true。调用resolve后，对象的父作用域
// 将设置为s。Squash通过将s的所有对象添加到p，将s的所有子对象添加到p的子对象，将s的所有子对象添加到p的子对象，并从p的子对象中删除s，从而将Squash与其父作用域p合并。
func (s *Scope) InsertLazy(name string, resolve func() Object) bool {
	if s.elems[name] != nil {
		return false
	}
	s.insert(name, &lazyObject{parent: s, resolve: resolve})
	return true
}

func (s *Scope) insert(name string, obj Object) {
	if s.elems == nil {
		s.elems = make(map[string]Object)
	}
	s.elems[name] = obj
}

// 函数f是为s中的每个对象obj调用的，其中
// 在p.s中有一个对象alt。在压缩
// 后，应丢弃该函数。
func (s *Scope) Squash(err func(obj, alt Object)) {
	p := s.parent
	assert(p != nil)
	for name, obj := range s.elems {
		obj = resolve(name, obj)
		obj.setParent(nil)
		if alt := p.Insert(obj); alt != nil {
			err(obj, alt)
		}
	}

	j := -1 // p.children中s的索引
	for i, ch := range p.children {
		if ch == s {
			j = i
			break
		}
	}
	assert(j >= 0)
	k := len(p.children) - 1
	p.children[j] = p.children[k]
	p.children = p.children[:k]

	p.children = append(p.children, s.children...)

	s.children = nil
	s.elems = nil
}

// Pos和End描述作用域的源代码范围[pos，end）.
// 仅当选中的类型
// AST具有完整的位置信息时，结果才保证有效。范围未定义
// 用于宇宙和包范围。
func (s *Scope) Pos() syntax.Pos { return s.pos }
func (s *Scope) End() syntax.Pos { return s.end }

// 包含pos是否在范围内的报告。
// 仅当类型选中ABCDEF时，结果才保证有效G
func (s *Scope) Contains(pos syntax.Pos) bool {
	return s.pos.Cmp(pos) <= 0 && pos.Cmp(s.end) < 0
}

// Innermost返回包含
// pos的最内层（子）作用域。如果pos不在任何作用域内，则结果为零。
// 对于宇宙范围，结果也是零。
// 只有当选中的类型
// AST具有完整的位置信息时，才能保证结果有效。
func (s *Scope) Innermost(pos syntax.Pos) *Scope {
	// 包作用域没有扩展数据块，因为它们可能是
	// 不连续的，所以迭代包的文件。
	if s.parent == Universe {
		for _, s := range s.children {
			if inner := s.Innermost(pos); inner != nil {
				return inner
			}
		}
	}

	if s.Contains(pos) {
		for _, s := range s.children {
			if s.Contains(pos) {
				return s.Innermost(pos)
			}
		}
		return s
	}
	return nil
}

// writet将作用域的字符串表示形式写入w，
// ，作用域元素按名称排序。
// 缩进级别由n>=0控制，如果没有缩进，则
// n==0。
// 如果设置了recurse，它还会写入嵌套（子）作用域。
func (s *Scope) WriteTo(w io.Writer, n int, recurse bool) {
	const ind = ".  "
	indn := strings.Repeat(ind, n)

	fmt.Fprintf(w, "%s%s scope %p {\n", indn, s.comment, s)

	indn1 := indn + ind
	for _, name := range s.Names() {
		fmt.Fprintf(w, "%s%s\n", indn1, s.Lookup(name))
	}

	if recurse {
		for _, s := range s.children {
			s.WriteTo(w, n+1, recurse)
		}
	}

	fmt.Fprintf(w, "%s}\n", indn)
}

// String返回作用域的字符串表示形式，用于调试。
func (s *Scope) String() string {
	var buf bytes.Buffer
	s.WriteTo(&buf, 0, false)
	return buf.String()
}

// lazyObject表示导入的对象尚未被其导入者完全解析。
type lazyObject struct {
	parent  *Scope
	resolve func() Object
	obj     Object
	once    sync.Once
}

// resolve返回由obj表示的对象，根据需要解析惰性
// 对象。
func resolve(name string, obj Object) Object {
	if lazy, ok := obj.(*lazyObject); ok {
		lazy.once.Do(func() {
			obj := lazy.resolve()

			if _, ok := obj.(*lazyObject); ok {
				panic("recursive lazy object")
			}
			if obj.Name() != name {
				panic("lazy object has unexpected name")
			}

			if obj.Parent() == nil {
				obj.setParent(lazy.parent)
			}
			lazy.obj = obj
		})

		obj = lazy.obj
	}
	return obj
}

// 存根实现，所以*lazyObject实现了Object，我们可以将它们直接存储到范围中。埃姆斯。
func (*lazyObject) Parent() *Scope                        { panic("unreachable") }
func (*lazyObject) Pos() syntax.Pos                       { panic("unreachable") }
func (*lazyObject) Pkg() *Package                         { panic("unreachable") }
func (*lazyObject) Name() string                          { panic("unreachable") }
func (*lazyObject) Type() Type                            { panic("unreachable") }
func (*lazyObject) Exported() bool                        { panic("unreachable") }
func (*lazyObject) Id() string                            { panic("unreachable") }
func (*lazyObject) String() string                        { panic("unreachable") }
func (*lazyObject) order() uint32                         { panic("unreachable") }
func (*lazyObject) color() color                          { panic("unreachable") }
func (*lazyObject) setType(Type)                          { panic("unreachable") }
func (*lazyObject) setOrder(uint32)                       { panic("unreachable") }
func (*lazyObject) setColor(color color)                  { panic("unreachable") }
func (*lazyObject) setParent(*Scope)                      { panic("unreachable") }
func (*lazyObject) sameId(pkg *Package, name string) bool { panic("unreachable") }
func (*lazyObject) scopePos() syntax.Pos                  { panic("unreachable") }
func (*lazyObject) setScopePos(pos syntax.Pos)            { panic("unreachable") }
